home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / system / almdn102.zip / ALARM.DOC < prev    next >
Text File  |  1995-01-26  |  38KB  |  917 lines
  1.  
  2.                          ┌────────────────────────┐
  3.                          │      Alarm v1.02       │
  4.                          │                        │
  5.                          │ Written by Dale Nurden │
  6.                          └────────────────────────┘
  7.  
  8.                       The FREEWARE alarm clock for DOS
  9.  
  10.  
  11.  
  12.                     Copyright (c) 1994-95 by Dale Nurden
  13.          All rights reserved. See distribution notice for details.
  14. ________________________________________________________________________________
  15.  
  16.  
  17.  CONTENTS ▄
  18.   ▀▀▀▀▀▀▀▀▀
  19.  
  20.      1. LEGAL STUFF
  21.           1. Distribution
  22.           2. Disclaimer
  23.  
  24.      2. ABOUT THE PROGRAM
  25.           1. Terminology
  26.  
  27.      3. INSTALLATION
  28.           1. Installing the Program Files
  29.           2. Changing your AUTOEXEC.BAT File
  30.  
  31.      4. ALARMTSR
  32.           1. Command Line Options
  33.           2. Features and Functions
  34.           3. Popup clock/status display
  35.           4. Tiny mode
  36.           5. Configuration
  37.           6. Error messages
  38.           7. TSR conflicts
  39.  
  40.      5. ALARM
  41.           1. Command Line Options
  42.           2. Features and Functions
  43.           3. Using the Editor
  44.           4. Configuration
  45.  
  46.      6. TECHNICAL INFORMATION
  47.           1. Third party software
  48.           2. Communicating with AlarmTSR
  49.           3. The Alarm Data File : ALARM.ALM
  50.           4. Alarm Configuration File : ALARM.CFG
  51.           5. AlarmTSR Configuration File : ALARMTSR.CFG
  52.  
  53.      7. PROGRAM LIMITATIONS
  54.  
  55.      8. SYSTEM REQUIREMENTS
  56.  
  57.      9. ACKNOWLEDGEMENTS
  58.  
  59.     10. CONTACTING THE AUTHOR
  60.  
  61. ________________________________________________________________________________
  62.  
  63.  
  64.  [1]  LEGAL STUFF ▄
  65.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  66.  
  67.  
  68. [1.1]  DISTRIBUTION
  69.        ~~~~~~~~~~~~
  70.  
  71. This package is FREEWARE. You are free to distribute it as much as you
  72. like, subject to the following conditions:
  73.  
  74. ■ No fee is charged for its distribution or use, except to cover media and
  75.   copying costs.
  76. ■ All the files listed in FILES.LST are included in the distribution
  77.   package, in their original, unmodified form.
  78.  
  79. This package may be bundled together with other Freeware or Shareware
  80. packages, subject to the same conditions above. Throughout this document,
  81. the term "the package" refers to all the files listed in FILES.LST, in
  82. either their expanded (normal) state or compressed in an archive created by
  83. such software as ARJ and PkZip.
  84.  
  85. Please note that while this package is Freeware, I retain the copyright on
  86. all the work in this package, with the exception of those parts of the code
  87. which I have taken from sources other than my own (see Chapter xxx,
  88. Acknowledgements). It is necessary to mention this since at the time of
  89. release it was not possible to recompile the main program (ALARM.EXE) to
  90. reflect the updated copyright message.
  91.  
  92.  
  93.  
  94. [1.2]  DISCLAIMER
  95.        ~~~~~~~~~~
  96.  
  97. The possession and use of any of the programs and files in this package is
  98. entirely at your own risk. Although every effort has been made to prevent
  99. it, the author will not be held responsible or liable for any loss or
  100. damage of any nature resulting from the possession or use of this package.
  101. As of this writing, no ill-effects have been experienced or reported but,
  102. unfortunately, there is always the chance that some strange and obscure
  103. combination of hardware and software could cause problems.
  104.  
  105. See Chapter 4.7 for more information on TSR conflicts. Please report any
  106. problems you may encounter to the author. See Chapter 10 for information on
  107. contacting the author.
  108.  
  109. ________________________________________________________________________________
  110.  
  111.  
  112.  [2]  ABOUT THE PROGRAM ▄
  113.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  114.  
  115.  
  116. This is an updated version of the first release of ALARM, the DOS based
  117. Alarm Clock. The update introduces a slightly redesigned AlarmTSR module
  118. which now displays the day of the week on the popup clock. It also removes
  119. the CPU detection routine, which was faulty. The main program (ALARM.EXE)
  120. has not been changed from Version 1.0; only AlarmTSR and the appropriate
  121. documentation has been updated.
  122.  
  123. ALARM makes use of your computer's real-time clock to maintain up to 100
  124. separate alarms, and to sound them at the appropriate times with accuracy
  125. down to one minute. Each alarm can be set individually with its own
  126. message, which will be displayed along with a reminder beep from the
  127. computer's built-in speaker. A built-in popup clock provides a convenient
  128. time-piece which is available at your fingertips with a single keystroke.
  129.  
  130. ALARM consists of two parts, an Alarm Editor to set, change and delete
  131. alarms as is necessary, and a memory resident module called AlarmTSR which
  132. takes care of sounding your alarms at the appropriate times. This memory
  133. resident module (also known as a TSR, or Terminate-and-Stay-Resident
  134. program) must be loaded into memory for ALARM to work correctly, and also
  135. for the popup clock to be available.
  136.  
  137.  
  138.  
  139. [2.1]  TERMINOLOGY
  140.        ~~~~~~~~~~~
  141.  
  142. Alarm    - This refers to the Alarm Editor, the file in this package with
  143.            the name ALARM.EXE.
  144. AlarmTSR - This refers to the memory resident module (TSR) called AlarmTSR,
  145.            the file in this package with the name ALARMTSR.EXE.
  146. ALARM    - The program as a whole, encompassing both Alarm (ALARM.EXE) and
  147.            AlarmTSR (ALARMTSR.EXE).
  148. TSR      - Terminate-and-Stay-Resident program. A program which, when run,
  149.            stays active in memory even after it appears to have finished.
  150.            AlarmTSR is such a program.
  151.  
  152.  
  153.  
  154. ________________________________________________________________________________
  155.  
  156.  
  157.  [3]  INSTALLATION ▄
  158.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  159.  
  160.  
  161. [3.1]  INSTALLING THE PROGRAM FILES
  162.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  163.  
  164. The first thing you will need to do is determine which directory will be
  165. used for the program files. Both Alarm and AlarmTSR will expect to find all
  166. the relevant files in the same directory in which they reside, so it is
  167. important that all the program files are in the same directory. Which
  168. directory you use is irrelevant, as long as ALL the files are in it.
  169.  
  170. Although it is not necessary, it is usually most convenient to create a
  171. separate directory for ALARM. In this documentation, it will be assumed
  172. that the directory to be used is called ALARM\ and is situated off the root
  173. directory of the C: drive. If you decide to use a different drive or
  174. directory, substitute the appropriate changes in the examples given.
  175.  
  176. If the directory does not already exist, you will need to create it. The
  177. command to create our example directory would be:
  178.  
  179.        MKDIR C:\ALARM
  180.  
  181. This is what will be referred to as the "Program Directory".
  182.  
  183. The final installation step is to copy the relevant files into this
  184. directory. You could simply extract the entire distribution archive into
  185. this directory, or you can copy the necessary files directly, using the DOS
  186. 'COPY' command. The file 'FILES.LST' lists all the files which should have
  187. been included in the distribution package. (If any are missing, notify the
  188. administrator of the source from which you obtained the package, and make
  189. sure you erase this package and fetch the proper package from a more
  190. reliable source.) Those files in FILES.LST which are marked with an
  191. asterisk are the ones which are essential for ALARM to work properly. They
  192. must be placed in the program directory. The others are documentation and
  193. support files, which may be stored elsewhere or erased on the condition
  194. that they are included if you ever redistribute ALARM to anyone else. In
  195. any case, you should make sure that you always have access to these files
  196. somehow in case you ever need to read them.
  197.  
  198. That's all there is to it. There are no environment variables that need
  199. setting, and you don't need to put this directory into your system path.
  200. All the program files are able to find the files they require as long as
  201. they are all in this directory. ALARM is now ready to be used.
  202.  
  203. There is one more step, which is discussed in the next section. That is to
  204. update your computer's startup files to make sure your computer is always
  205. ready to run ALARM every time you switch it on.
  206.  
  207.  
  208.  
  209. [3.2]  UPDATING YOUR AUTOEXEC.BAT FILE
  210.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  211.  
  212. In order to use ALARM properly, AlarmTSR (the memory resident module) must
  213. always be loaded into memory. It is usually most convenient to have it
  214. loaded automatically for you whenever you start or reboot your computer.
  215. This can be done simply by adding a line to your AUTOEXEC.BAT file, which
  216. is a DOS batch file which runs automatically every time you restart your
  217. computer. The line to be added is:
  218.  
  219.        C:\ALARM\ALARMTSR
  220.  
  221. (This assumes that you have chosen our example directory to be your program
  222. directory. See Chapter 3.1, above.)
  223.  
  224. If your computer is capable of loading programs in the upper memory area,
  225. you can use the following line instead:
  226.  
  227.        LOADHIGH C:\ALARM\ALARMTSR
  228.  
  229. You will need at least 3k of memory free in the upper memory area in order
  230. to load the TSR, of which 2.5k will be used, with the remainder being
  231. released after loading. It is possible to load AlarmTSR in "Tiny" mode by
  232. using the 'T' option on the command line. See Chapters 4.1 and 4.4 for more
  233. information.
  234.  
  235. It is also possible to have the alarm data file automatically updated for
  236. you at the same time that AlarmTSR is loaded. This is useful since it saves
  237. you from having to remember to update the file every few days, a task which
  238. is necessary if not done automatically. See Chapter 5 for more information.
  239. Adding the following line to your AUTOEXEC.BAT file will do just this:
  240.  
  241.        C:\ALARM\ALARM /U
  242.  
  243. Both of these changes can be made automatically for you using the
  244. ALARMBAT.BAT batch file which is included in the package. This program will
  245. first save a backup copy of your AUTOEXEC.BAT file, then add the above two
  246. lines. ALARMBAT.BAT always assumes that your AUTOEXEC.BAT file is in the
  247. root directory of C:, so if it is not, you will have to make the changes
  248. yourself. Also, ALARMBAT.BAT does not insert the "LOADHIGH" version of the
  249. first change, so if you want AlarmTSR to make use of your upper memory
  250. area, you will need to make that change yourself.
  251.  
  252. Remember that it is preferable, though not necessary, to update the alarm
  253. data file BEFORE loading AlarmTSR. ALARMBAT.BAT makes the changes in the
  254. correct order, but if you choose to make the changes yourself, you should
  255. also observe this point.
  256.  
  257. ________________________________________________________________________________
  258.  
  259.  
  260.  [4]  ALARMTSR ▄
  261.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  262.  
  263.  
  264. AlarmTSR is the memory resident module (TSR) which works in conjunction
  265. with Alarm to sound your alarms at appropriate times. To overly simplify
  266. matters, AlarmTSR sits in memory and quietly waits for the appropriate time
  267. before sounding an alarm. AlarmTSR MUST be installed in memory for ALARM to
  268. function correctly. See Chapter 3 for details on simplifying the
  269. installation process.
  270.  
  271. AlarmTSR will only load once, so if it is already installed in memory and
  272. you try to reload it, it will fail with a warning message.
  273.  
  274.  
  275.  
  276. [4.1]  COMMAND LINE OPTIONS
  277.        ~~~~~~~~~~~~~~~~~~~~
  278.  
  279. There is only one option which may be specified on the command line. The
  280. 'T' option instructs AlarmTSR to install in Tiny mode. If you do not
  281. specify this option, AlarmTSR will install in normal mode. See Chapter 4.4
  282. for details on Tiny mode.
  283.  
  284. The command syntax is:   ALARMTSR [T]
  285.  
  286.  
  287.  
  288. [4.2]  FEATURES AND FUNCTIONS
  289.        ~~~~~~~~~~~~~~~~~~~~~~
  290.  
  291. AlarmTSR periodically checks the alarm data file (see Chapter 6.3) for
  292. information about the alarms you have set. It searches through the data
  293. file for the first alarm which has not already passed (that is, its time
  294. and date is before the current time and date on your computer's clock) and
  295. then stores it in memory. In fact, this search is only performed when an
  296. alarm is sounded (to load the next alarm), or when AlarmTSR is specifically
  297. instructed to do so, either by your using Alarm and the 'R' option, or when
  298. you exit Alarm (the alarm editor).
  299.  
  300. AlarmTSR also periodically checks whether the current alarm matches the
  301. current time on the computer's real time clock, and then sounds the alarm
  302. if they do match.
  303.  
  304. The final two features, the popup clock/status display and AlarmTSR's Tiny
  305. mode, are discussed in Chapters 4.3 and 4.4.
  306.  
  307.  
  308.  
  309. [4.3]  POPUP CLOCK/STATUS DISPLAY
  310.        ~~~~~~~~~~~~~~~~~~~~~~~~~~
  311.  
  312. Apart from checking for and sounding alarms, AlarmTSR also features a
  313. built-in popup clock/status display which is hotkey activated, the default
  314. hotkey being Ctrl-T. This display appears when the hotkey is pressed and
  315. held down, and disappears when it is released.
  316.  
  317. The clock part (on the left of the display) shows the current time and date
  318. according to your computer's real time clock, with the display formats
  319. depending on how you have configured AlarmTSR (see Chapter 4.5). The clock
  320. is automatically updated while it is on the display.
  321.  
  322. The "alarm" part (on the right of the display) indicates the date and time
  323. at which the next alarm will be sounded. In addition, if it due to be
  324. sounded on the same day, an asterisk will appear after the date. Again, the
  325. display formats depend on how you have configured AlarmTSR. If there are no
  326. further alarms set, then the time and date will be filled with dashes.
  327.  
  328. If the "alarm" part is missing from the clock/status display, then you will
  329. know that AlarmTSR was loaded in Tiny mode.
  330.  
  331. The clock/status display appears as follows:
  332.  
  333.   ▌ 12:26:04p  Sun, 13 Feb 1994 ▐  Alarm:  4:15p  13/02/1994 *   │
  334.                                                        
  335.        │    │         │                     │  │      │      │
  336.        1    2         3                     4  5      6      7
  337.  
  338. 1. Current time, indicating hour, minute and seconds, as read from the
  339.    computer's real time clock. This may be in 12-hour or 24-hour format,
  340.    but defaults to 12-hour format if not configured.
  341. 2. AM/PM indicator. This does not appear in 24-hour format.
  342. 3. Current date, indicating day, month, year and day of week.
  343. 4. Time of the next alarm to be sounded, indicating hour and minute only.
  344.    AlarmTSR does not allow seconds accuracy partly because this is seldom
  345.    required, but mainly because an alarm may be delayed a few seconds if
  346.    the computer is busy.
  347. 5. AM/PM indicator. This does not appear in 24-hour format.
  348. 6. Date of the next alarm, indicating day, month and year.
  349. 7. Indicates that the current alarm will be sounded today.
  350.  
  351.  
  352.  
  353. [4.4]  TINY MODE
  354.        ~~~~~~~~~
  355.  
  356. This is a special mode for AlarmTSR which reduces its memory requirements
  357. as well as its functionality. In Tiny mode, AlarmTSR still provides the
  358. hotkey activated popup clock, but none of the alarm functions are
  359. available. This is intended for users who would like to keep the clock, but
  360. have no need for alarms.
  361.  
  362. AlarmTSR takes up 40% less memory in Tiny mode. The same amount of memory
  363. is required to load AlarmTSR, but only about 1.7k is retained, as opposed
  364. to the 2.8k that normal mode requires.
  365.  
  366. To load AlarmTSR in Tiny mode, the 'T' option must be used on the command
  367. line during installation. See Chapter 4.1.
  368.  
  369.  
  370.  
  371. [4.5]  CONFIGURATION
  372.        ~~~~~~~~~~~~~
  373.  
  374. AlarmTSR reads its configuration file (ALARMTSR.CFG - See Chapter 6.5) once
  375. when AlarmTSR is installed, if the file exists in the program directory.
  376. This configuration file contains information about how AlarmTSR should
  377. operate, including time and date display formats and display colours and is
  378. created and updated by Alarm. AlarmTSR is actually configured from inside
  379. Alarm (the alarm editor) from the Configuration menu (Alt-C).
  380.  
  381. If the configuration file does not exist in the program directory, AlarmTSR
  382. will assume default settings. If, at any time, you wish to restore these
  383. default settings, simply delete the appropriate configuration file.
  384.  
  385. Note: ALARMTSR.CFG also contains information about the hotkeys used by
  386.       AlarmTSR, but this is not yet supported by Alarm's configuration.
  387.       (This is likely to be included in future releases.) It is possible to
  388.       change the hotkeys used if you manually edit the configuration file,
  389.       but you should not attempt this unless you have some degree of
  390.       experience in such matters. See Chapter 6.5 for more information.
  391.  
  392.  
  393.  
  394. [4.6]  ERROR MESSAGES
  395.        ~~~~~~~~~~~~~~
  396.  
  397. There are two error messages which AlarmTSR will display under certain
  398. conditions:
  399.  
  400. "Unable to open alarm data file."
  401.        This means that the alarm data file (ALARM.ALM) is not in the
  402.        program directory. It should never be deleted or moved to another
  403.        directory, even if no alarms have been set, since AlarmTSR
  404.        periodically checks it for new alarms.
  405.  
  406. "Alarm data file is corrupt."
  407.        This means that the alarm data file (ALARM.ALM) does exist, but the
  408.        information contained in it is not in the format AlarmTSR is
  409.        expecting, which means that it has become corrupted somehow. The
  410.        only way to correct this problem is to delete the file and then run
  411.        Alarm to create a new file. In doing so you will lose any alarms you
  412.        have set, but this is unfortunately unavoidable. If this error
  413.        occurs, you should investigate it further because it could be
  414.        indicative of a hardware failure.
  415.  
  416.  
  417.  
  418. [4.7]  TSR CONFLICTS
  419.        ~~~~~~~~~~~~~
  420.  
  421. The unfortunate fact about memory resident (TSR) programs is that sometimes
  422. two or more may conflict because of the way they operate. AlarmTSR has been
  423. tested with a few other TSR programs in various conditions, and has been
  424. successfully used on the author's own computer without complications. While
  425. no conflicts were found through this testing, this can unfortunately not
  426. guarantee that conflicts will not occur with other hardware and software
  427. configurations. If you experience difficulties with AlarmTSR or any other
  428. TSR program while using Alarm or AlarmTSR, please contact the author with
  429. details of your problem and your hardware and software configurations.
  430. Copies of your AUTOEXEC.BAT and CONFIG.SYS files may also help. Doing this
  431. will ensure that a similar problem won't appear in future releases of
  432. ALARM.
  433.  
  434. AlarmTSR makes use of the Alternate Multiplex interrupt for communication
  435. (See Chapter 6.2). Since this is also sometimes used by other programs, is
  436. it possible that two programs could have the same ID byte, which is what is
  437. used to identify individual programs. If this problem does occur, the
  438. symptoms will most probably be one of the TSRs not working correctly (the
  439. one which loaded earlier would most likely become faulty). Unfortunately,
  440. there is no way to correct this problem. The next release of ALARM is
  441. likely to have the ability to change its ID byte to cope with this
  442. situation.
  443.  
  444. ________________________________________________________________________________
  445.  
  446.  
  447.  [5]  ALARM ▄
  448.   ▀▀▀▀▀▀▀▀▀▀▀
  449.  
  450.  
  451. Alarm is the alarm editor, which is used to set, change and delete alarms
  452. as required. It is run interactively from the command line without options,
  453. although there are some options available for tasks that don't require the
  454. full editor. These options are discussed in Chapter 5.1.
  455.  
  456. Alarm creates and maintains the alarm data file, if one does not already
  457. exist in the program directory, and stores all the information about the
  458. alarms you have set in it. This file is used by both Alarm for its own
  459. purposes, and by AlarmTSR. Alarm also creates and maintains the
  460. configuration files ALARM.CFG and ALARMTSR.CFG when you make changes to the
  461. program's default settings.
  462.  
  463. At the time of release of this update, it was not possible to recompile the
  464. main program. For this reason, the main display will still reflect Version
  465. 1.0 of the software even though it should be Version 1.02. This does not
  466. affect the functionality of the program in any way.
  467.  
  468.  
  469.  
  470. [5.1]  COMMAND LINE OPTIONS
  471.        ~~~~~~~~~~~~~~~~~~~~
  472.  
  473. The command syntax for Alarm is:
  474.  
  475.        ALARM [[/ | -]option]
  476.  
  477. Options may be preceded by a slash (DOS convention) or a dash (UNIX
  478. convention) although it is not necessary. The options are of the nature
  479. that no two can be used together on the command line.
  480.  
  481. The following options are available:
  482.  
  483. D - Disable the current alarm.
  484.     This option clears the current alarm from AlarmTSR's memory, so that it
  485.     will not be sounded. Since AlarmTSR only reads the next alarm when the
  486.     current alarm is sounded, no further alarms will be sounded until
  487.     AlarmTSR is specifically instructed to re-read the alarm data file
  488.     (which is done when you exit Alarm or by running Alarm with the 'R'
  489.     option). The status display will also indicate that no further alarms
  490.     have been set.
  491.     This option is provided in case you use a program which should not
  492.     be interrupted by an alarm. You could, in this case, create a batch
  493.     file which disables alarms, runs your program, then re-enables alarms
  494.     when you exit your program. Remember that the Ctrl-T hotkey will still
  495.     be active, so if this is likely to cause problems you should avoid
  496.     pressing it.
  497.     In the process of re-enabling alarms (with the 'R' option), the current
  498.     alarm is also updated. This means that any alarms which would have
  499.     sounded while you were running your program will be missed. You should
  500.     be aware of this and take appropriate action.
  501.  
  502. M - Force monochrome colours for the editor
  503.     This option forces the editor to start run with the default monochrome
  504.     colour set, in case you are using a monochrome monitor. You will still
  505.     be able to make changes to the colours using Alarm's configuration menu
  506.     but remember that if you save your configuration, the colours currently
  507.     in use will be saved and used every time in future.
  508.     If you start in monochrome mode, then save your configuration, the
  509.     colours will always be monochrome whenever you use the editor from then
  510.     on.
  511.     You can restore the default colours by deleting the configuration file
  512.     ALARM.CFG in the program directory.
  513.  
  514. R - Force AlarmTSR to re-read the alarm data file
  515.     This option forces AlarmTSR to update itself by re-reading the alarm
  516.     data file. This function is automatically invoked when you exit Alarm.
  517.     The main use of this function is to re-enable alarms after they have
  518.     been disabled using the 'D' option.
  519.  
  520. U - Update alarm data file
  521.     This function has the same effect as pressing Alt-U while inside the
  522.     editor. It updates the alarm data file by removing all alarms which
  523.     have already passed. This can be useful since old alarms can slow down
  524.     operation of AlarmTSR if not removed.
  525.     You could make changes to your AUTOEXEC.BAT file so that this option is
  526.     selected every time your computer is started or rebooted (see Chapter
  527.     3.2), but remember that it is more efficient to do this BEFORE you load
  528.     AlarmTSR, although this is not critical.
  529.  
  530. UNINSTALL - Uninstall AlarmTSR
  531.     This option requests AlarmTSR to uninstall itself. If possible,
  532.     AlarmTSR will remove itself from memory. If not, you will be warned.
  533.     Uninstallation of a memory resident program is not always possible
  534.     if other memory resident programs have been loaded after it, because
  535.     of the way in which these programs work.
  536.     Note that you only need to specify as far as "UN" on the command line
  537.     for uninstallation to be attempted, so you should be careful not to
  538.     accidentally add an 'N' when using the 'U' (Update) command, otherwise
  539.     AlarmTSR could be removed unintentionally. Of course, you could always
  540.     reinstall AlarmTSR without any ill effects.
  541.  
  542.  
  543.  
  544. [5.2]  FEATURES AND FUNCTIONS
  545.        ~~~~~~~~~~~~~~~~~~~~~~
  546.  
  547. When used in interactive mode (without command line parameters), the main
  548. display screen will appear, listing all the alarm which you have already
  549. set. From here, you can move around the alarm list and make additions,
  550. changes and deletions as you wish.
  551.  
  552. The two main features of Alarm, apart from its obvious editing features,
  553. are the automatic alarm updating and the configuration menu features. Alarm
  554. can be set to update the alarm data file automatically (by deleting all
  555. alarms which have already passed) every time it is run interactively, with
  556. or without prompting.
  557.  
  558. The update feature (Alt-U) in itself is useful since it saves you from
  559. having to delete your old alarms manually.
  560.  
  561. The configuration menus (Alt-C) are used to customise the operation of
  562. both Alarm and AlarmTSR.
  563.  
  564. Remember that at all times, online help is available by pressing F1. This
  565. is often useful for explaining what you are about to do, and in some cases
  566. is even mentions shortcuts for certain tasks, which are otherwise
  567. undocumented.
  568.  
  569.  
  570.  
  571. [5.3]  USING THE EDITOR
  572.        ~~~~~~~~~~~~~~~~
  573.  
  574. Using the editor itself is quite straightforward and self-explanatory.
  575. The best way to figure out how to use the editor is simply to get into it
  576. and try things out. For the first few days you should look at the online
  577. help (F1) every time you come across something new, since this will give
  578. you a much better understanding of the program's operation than any offline
  579. documentation is likely to give.
  580.  
  581.  
  582.  
  583. [5.4]  CONFIGURATION
  584.        ~~~~~~~~~~~~~
  585.  
  586. The configuration menus in the editor (Alt-C) are used to customise the
  587. program's options and operation. You can adjust colours, display formats
  588. and various other parameters from these menus.
  589.  
  590. AlarmTSR is also configured from these menus, in a submenu called "TSR
  591. options...". Note that while this is a sub-menu of the configuration menu,
  592. the AlarmTSR configuration options are treated separately by the program,
  593. and are even saved to separate configuration files.
  594.  
  595. It is important to remember that AlarmTSR only reads its configuration file
  596. when it is installed. This means that if you make any changes to AlarmTSR's
  597. configuration, you must uninstall and then reinstall it before the new
  598. configuration will become effective. If uninstallation is not possible then
  599. you will have to reboot your computer.
  600.  
  601. ________________________________________________________________________________
  602.  
  603.  
  604.  [6]  TECHNICAL INFORMATION ▄
  605.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  606.  
  607.  
  608. This section contains various information about the operation of ALARM. It
  609. is provided mainly for the sake of general interest, although it may be
  610. used for the development of third party products under certain conditions.
  611. See Chapter 6.1 for details.
  612.  
  613. NB! While backward compatibility is usually an issue for software
  614.     development, the author does not guarantee that any of the information
  615.     given here is entirely correct, neither does he undertake to maintain
  616.     these formats in future releases of ALARM.
  617.     Because it is documented here does not mean it will stay this way!
  618.  
  619.  
  620.  
  621. [6.1]  THIRD PARTY SOFTWARE
  622.        ~~~~~~~~~~~~~~~~~~~~
  623.  
  624. Third party software is considered to be software intended for use with
  625. ALARM, but written by some person other than the original author of ALARM.
  626. The development and distribution of third party software for ALARM is
  627. perfectly acceptable, subject to the following conditions:
  628.  
  629. 1. The third party software is distributed as Freeware, ie: No charge is
  630.    made for its distribution and use, except to cover media and copying
  631.    costs.
  632. 2. The author of Alarm and its associated programs and files is
  633.    acknowledged and mentioned in the documentation and/or program.
  634. 3. The author of Alarm is notified of the distribution of the third party
  635.    software package, and is given a copy thereof, free of charge. This need
  636.    not include the source, but should include the entire distribution
  637.    package including all documentation. A copy of the source would be
  638.    appreciated nonetheless.
  639.  
  640.  
  641.  
  642. [6.2]  COMMUNICATING WITH ALARMTSR
  643.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  644.  
  645. It is possible for external programs (such as Alarm) to communicate with
  646. AlarmTSR via the Int 2D Alternate Multiplex Interrupt. AlarmTSR's ID byte
  647. is fixed at D4h. To use any of the functions, load AH with the ID byte
  648. (D4h) and AL with the function number.
  649.  
  650. The following functions are available:
  651.  
  652.  
  653. FUNCTION 0 : Installation Check
  654.  
  655.         Input:  AX = D400
  656.  
  657.         Return: AL = DD
  658.                 AH = 00h if complete TSR is installed
  659.                      80h if the tiny TSR is installed (clock only)
  660.                 DH = Major version number
  661.                 DL = Minor version number
  662.  
  663.         Note: AlarmTSR v1.02 will report its version number as 1.0 for
  664.         compatibility with the old ALARM.EXE program.
  665.  
  666.  
  667. FUNCTION 1 : Uninstall TSR
  668.  
  669.         Input:  AX = D401
  670.  
  671.         Return: AL = 00 if ok
  672.                      FF if unable to uninstall
  673.  
  674.  
  675. FUNCTION 2 : Read Alarm Data File
  676.  
  677.         Input:  AX = D402
  678.  
  679.         Return: AL = 0 if successful, and there is are no more alarms
  680.                      1 if successful, and a new alarm was installed
  681.                      2 if an error occurred
  682.  
  683.         This function forces the TSR to re-read the alarm data file and
  684.         update the next alarm. This is intended to be called by the control
  685.         program when it has made changes.
  686.  
  687.  
  688. FUNCTION 3 : Disable Current Alarm
  689.  
  690.         Input:  AX = D403
  691.  
  692.         Return: none
  693.  
  694.         This function disables the current alarm if one has been set in the
  695.         TSR. Function 2 (Read Alarm Data File) may be used to reverse this
  696.         function.
  697.  
  698.  
  699.  
  700. [6.3]  THE ALARM DATA FILE : ALARM.ALM
  701.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  702.  
  703. This file contains all the information about the alarms you have set, and
  704. is used by Alarm to store the entire database, and by AlarmTSR to read the
  705. data for the next alarm to be sounded. Bearing in mind that this is subject
  706. to change in future releases of ALARM, the file format is as follows:
  707.  
  708.  
  709.    File offset
  710.      │
  711.      └── 0    1      86   87     172
  712.         ┌───┬─────//─────┬─────//─────┬─────//─────┬─
  713.         │   │  Record 1  │  Record 2  │  Record 3  │  etc...
  714.         └───┴─────//─────┴─────//─────┴─────//─────┴─
  715.                  
  716.           │       └─────── (86 bytes) One record
  717.           └─────────────── (1 byte) Number of records in file
  718.  
  719.  
  720.    Each record is as follows:
  721.  
  722.    Record offset
  723.      │
  724.      └── 0   1   2   3   4   5    6      85
  725.         ┬───┬───┬───┬───┬───┬───┬─────//─────┬
  726.         │   │   │   │   │   │   │            │
  727.         ┴───┴───┴───┴───┴───┴───┴─────//─────┴
  728.                                 
  729.           │   │   │   │   │   │       └──────── (80 bytes) Alarm message *
  730.           │   │   │   │   │   └──────────────── (1 byte) Minute
  731.           │   │   │   │   └──────────────────── (1 byte) Hour
  732.           │   │   │   └──────────────────────── (1 byte) Year
  733.           │   │   └──────────────────────────── (1 byte) Century
  734.           │   └──────────────────────────────── (1 byte) Month
  735.           └──────────────────────────────────── (1 byte) Day of month
  736.  
  737.    * Only 48 characters are actually used in the alarm message. The full 80
  738.      are permissible, but the "(Press Ctrl-Enter)" message will be
  739.      overwritten if this is done.
  740.  
  741.  
  742.  
  743. [6.4]  ALARM CONFIGURATION FILE : ALARM.CFG
  744.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  745.  
  746. This configuration file contains information about the settings for Alarm,
  747. the alarm editor. Bearing in mind that this is subject to change in future
  748. releases of ALARM, the file format is as follows:
  749.  
  750.    Offset  Default  Description
  751.       0      71h   Colour of title bar
  752.       1      71h   Colour of keybar descriptions
  753.       2      74h   Colour of keybar keys
  754.       3      70h   Colour of clock
  755.       4      1Fh   Colour of table lines
  756.       5      17h   Colour of normal text on table
  757.       6      71h   Colour of highlighted text on table
  758.       7      31h   Colour of edit window
  759.       8      13h   Colour of highlight in edit window
  760.       9      6Eh   Colour of delete and update windows
  761.      10      7Fh   Colour of configuration windows
  762.      11      3Fh   Colour of highlights in configuration windows
  763.      12      71h   Colour of exit window
  764.      13      5Fh   Colour of information windows
  765.      14      20h   Colour of help windows
  766.      15      4Eh   Colour of error windows
  767.      16      00h   Time format (0=12-hour, 1=24-hour)
  768.      17      00h   Auto-update mode (0=Off, 1=Prompt, 2=On)
  769.  
  770.  
  771.  
  772. [6.5]  ALARMTSR CONFIGURATION FILE : ALARMTSR.CFG
  773.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  774.  
  775. This configuration file contains information about the settings for
  776. AlarmTSR, the memory resident module. Remember that this file is only read
  777. when AlarmTSR is installed, so if you make any changes to it, you need to
  778. uninstall and then reinstall AlarmTSR for them to become effective. Bearing
  779. in mind that this is subject to change in future releases of ALARM, the
  780. file format is as follows:
  781.  
  782.    Offset  Default  Description
  783.      0       14h   Hotkey make code
  784.      1       94h   Hotkey break code
  785.      2       04h   Hotkey shift mask
  786.      3       1Ch   Clear alarm key make code
  787.      4       04h   Clear alarm key shift mask
  788.      5       70h   Popup colour
  789.      6       4Fh   Clock colour
  790.      7       00h   Time format (0=12-hour, 1=24-hour)
  791.      8       00h   Date format (0=DD/MM/YY, 1=MM/DD/YY)
  792.    9-23  "Ctrl-Enter"  Clear key description (15 bytes)
  793.  
  794. ________________________________________________________________________________
  795.  
  796.  
  797.  [7]  PROGRAM LIMITATIONS ▄
  798.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  799.  
  800.  
  801. For memory allocation purposes, only up to 100 alarms can be handled by
  802. Alarm. After this limit, you will not be permitted to add any more. The 100
  803. alarm limit is arbitrarily set, and it is possible to increase this number
  804. if required. To do so, you will need to contact the author for a customised
  805. version of ALARM. AlarmTSR itself can work with any number of alarms and is
  806. not limited to 100, but you should realise that more alarms in the database
  807. may cause AlarmTSR to operate slower than normal.
  808.  
  809. The other major limitation, which should be addressed in a future release
  810. of ALARM, is that AlarmTSR will only function correctly while your computer
  811. is in text mode (mono or colour 80-columns). Before attempting to display
  812. the clock/status or any alarm messages, AlarmTSR checks the video mode. If
  813. it is found to be anything other than one of the normal text modes, the
  814. display will not be permitted. In the case of alarms and error messages,
  815. the beep will still be sounded with no accompanying message; in the case of
  816. the popup clock/status, a warning beep will be sounded in place of the
  817. clock. The inspiration for ALARM came from a similar Windows-based program.
  818. Since the author is not a very happy Windows user, a text mode equivalent
  819. would have been more appropriate, hence ALARM was conceived. If you are a
  820. frequent graphics user, then ALARM is unfortunately not very suited for
  821. you.
  822.  
  823. Note that AlarmTSR will work in a DOS text window in Windows, in both
  824. fullscreen and windowed modes. So you can still use Alarm in Windows, as
  825. long as you have a DOS window open somewhere (and running in background
  826. mode if necessary). Be warned, however, that I have had trouble with the
  827. popup clock/status not disappearing from a DOS window when the hotkey is
  828. released. I haven't been able to find the cause of this apparently random
  829. problem yet, but it only occurs in a windowed DOS window, not when you are
  830. in full screen mode.
  831.  
  832. ________________________________________________________________________________
  833.  
  834.  
  835.  [8]  SYSTEM REQUIREMENTS ▄
  836.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  837.  
  838.  
  839. The following are considered the minimum requirements to successfully run
  840. ALARM:
  841.  
  842. ■ 80286 microprocessor minimum.
  843. ■ 3k memory to load the TSR (when resident, uses 2.8k in normal mode or
  844.   1.7k in Tiny mode).
  845. ■ At least 128k memory for Alarm.
  846. ■ About 110k on your disk (to store the entire distribution package
  847.   uncompressed - less if you only keep the essential files).
  848. ■ Text video mode (hopefully autodetects monochrome or colour mode)
  849. ■ MS-DOS 3.1 or greater (actually, it has only been tested under DOS 5, but
  850.   there's no reason for not working under v3.1 and later).
  851.  
  852.  
  853. ALARM has been subjected to work testing on the following system, with
  854. favourable results:
  855.  
  856.    386DX-40
  857.    512k VGA
  858.    Quite a bit of DOS memory
  859.    A whole bunch of hard drive space
  860.    MS-DOS 5
  861.  
  862. ________________________________________________________________________________
  863.  
  864.  
  865.  [9]  ACKNOWLEDGEMENTS ▄
  866.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  867.  
  868.  
  869. Well, not all of the code in this project is my own work. My special thanks
  870. go to the following:
  871.  
  872. ■ Owens Consulting and Jeff Owens:
  873.   ALIB v1.0, Copyright (c) 1994 by Owens Consulting and Jeff Owens
  874.   (Time and date calculation routines for AlarmTSR)
  875. ■ Carl Schei:
  876.   (For various little code bits, especially with regards to beeping the PC
  877.   speaker in AlarmTSR)
  878.  
  879. Obviously, my copyright cannot cover their work, since they already own
  880. their respective copyrights.
  881.  
  882. ________________________________________________________________________________
  883.  
  884.  
  885.  [10]  CONTACTING THE AUTHOR ▄
  886.   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  887.  
  888.  
  889. If you like this package and have any comments to share, please send me a
  890. postcard. Postcards do wonders for my ego, and they're a nice, inexpensive
  891. way of acknowledging the work I've put into developing this FREE software.
  892.  
  893. And if you include an Email address then I'll be able to keep you informed
  894. about new releases of ALARM.
  895.  
  896.  
  897. Snailmail: Dale Nurden
  898.  
  899.            14 Willow Crescent
  900.            Pinetown
  901.            3610
  902.            South Africa
  903.  
  904.  
  905.  Internet: dalen@goofy.iaccess.za    (My apologies to anyone who may have
  906.                                       tried to contact me at my old email
  907.                                       address, which is obviously no longer
  908.                                       in existence.)
  909.  
  910.  
  911.       BBS: Connectix BBS, UserID: Tech
  912.              (+2731) international, (031) national
  913.              2669992-7 (6 lines, 14400-N81)
  914.  
  915. ________________________________________________________________________________
  916.  
  917.